Write Sub-unit

Description

Sets all outputs of a sub-unit to the supplied bit-pattern. The number of least significant bits corresponding to the size of the sub-unit are written.

Prototype

DWORD PIPLX_WriteSub(SESSION Session, DWORD CardNum, DWORD OutSub, DWORD *Data, DWORD DataLen);

Parameters:

Session - The session variable obtained from the PICMLX_Connect call

CardNum - card number

OutSub - output sub-unit number

Data - pointer to the one-dimensional array (vector) containing the bit-pattern to be written

DataLen - length of the above array in BYTES (Note - BYTES not DWORDs !)

Returns:

Zero for success, or non-zero error code.

Note

For a Matrix sub-unit, the data is folded into the vector on its row-axis: see Data Formats.

Warning

The data array pointed to must contain sufficient bits to represent the bit-pattern for the specified sub-unit, or undefined data will be written to the more significant bits.

Example Code

For clarity, this example omits initialising the variables CardNum, OutSub etc. and does no error-checking.

/* Dimension a DWORD data array to contain the number of bits

  necessary to represent the sub-unit (e.g. 2 longwords

  supports sub-units having upto 64 switches) */

DWORD Data[2]; /* Value specifies the number of array elements */

/* Data[0] bit 0 represents switch #1

  Data[0] bit 1 represents switch #2

  ... etc.

  Data[0] bit 31 represents switch #32

  Data[1] bit 0 represents switch #33

  ... etc. */

/* Setup array data to turn on switches 3, 33 and output to the card */

Data[0] = 0x00000004UL; /* set DWORD 0 bit 2 (switch 3) */

Data[1] = 0x00000001UL; /* set DWORD 1 bit 0 (switch 33) */

Result = PIPLX_WriteSub(Session, CardNum, OutSub, Data);

/* Add switch 4 to the array and output to the card */

Data[0] |= 0x00000008UL; /* set DWORD 0 bit 3 (switch 4) */

Result = PIPLX_WriteSub(Session, CardNum, OutSub, Data);

/* ... now have switches 3, 4, 33 energised */

/* Delete switch 33 from the array and output to the card */

Data[1] &= 0xFFFFFFFEUL; /* clear DWORD 1 bit 0 (switch 33) */

Result = PIPLX_WriteSub(Session, CardNum, OutSub, Data);

/* ... leaving switches 3 and 4 energised */